Day23：Ant Design 裡的 Form 表單(part1)

2022 iThome 鐵人賽

DAY 23

自我挑戰組

那些年我用 Ant Design 做過的網頁元件系列第 23 篇

14th鐵人賽

Annie

2022-10-08 23:55:37

1376 瀏覽

分享至

Form 表單這系列的文章在 Day04~08 時(註1~4)有分享了比較常見的表單元件，為了將ANTD表單完整功能做個統整，從今天開始大約會花2~3篇文章篇幅將使用方法再做細說。和其他元件一樣，ANTD 的表單整體而言功能可說是一應俱全，像是初始值、驗證、提交動作、客製化樣式與動態新增欄位等，也有針對 React Hook 和 class component 做不同的案例解說，今天就讓我們開始認識它吧！

一、ANTD Table 最基本的使用方式：引用與呼叫它

基本上 Form 是主體標籤，裡面的每一個輸入框(或稱填寫欄位)都須使用 <Form.Item> tag包起來，這樣可以方便讓 Form 的表單監聽事件中抓取該表單每個欄位的變化，另外要記得搭配一個 htmlType="submit" 的 button，實際送出的事件則是綁在 Form 表單的 onFinish function 裡。

import { Form, Button } from 'antd';

const App = () => (
  <div>
    <Form
      name="basic"
      labelCol={{span: 8}}
      wrapperCol={{span: 16}}
      initialValues={{}}
      onFinish={handleFinish}
      onValuesChange={handleValuesChange}
    >
      <Form.Item
        label="姓名"
        name="name"
        rules={[
          {
            required: true,
            message: '請輸入姓名',
          },
        ]}
      >
        <Input />
      </Form.Item>
      <Form.Item>
        <Button type="primary" htmlType="submit">
          送出
        </Button>
      </Form.Item>
    </Form>
  <div/>
);

export default App;

二、Form 可添加的參數

以下列出我個人比較常用的，參數就如同下方程式碼說明，也可以點此連結去看更多官方 api 文件。比較方便的是labelCol與wrapperCol兩個參數，它們是拿來設定label和input的比例，如果你的表單項目是inline-style，希望label佔1/3、input佔2/3，那可以使用labelCol={{span: 8}} wrapperCol={{span: 16}}來達成，因為在表單裡也遵循ANTD的Grid rules，總計為24等份的規則。

屬性名稱	可以使用的值	說明
layout	horizontal 或 vertical 或 inline	設定整個表單的每個`<Form.Item>` 的label和input的排列方式。預設是水平佈滿(horizontal)。
labelCol	object	設定整個表單的每個`<Form.Item>` 的label佔據比例
labelWrap	true 或 false	設定整個表單的每個`<Form.Item>` 的label，是否在寬度有限的狀況下自動換行。預設是false
wrapperCol	object	設定整個表單的每個`<Form.Item>` 的input佔據比例
initialValues	object	設定表單中的預設值(或初始值)
colon	true 或 false	設定是否顯示每個`<Form.Item>` 的label和input中間的冒號，預設true。
name	字串	其實等同於表格的id
onValuesChange	`(changedValues, allValues) => {}`	當表單值一有變動時會觸發的function，第一個參數是指有變動的，第二個參數則是指全部的。可視情形取用。
onFinish	`(values) => {}`	當按下表單送出鈕時，會觸發的function，而參數values搭配label名稱，則可以得到對應的輸入值。
scrollToFirstError	true 或 false	當表單送出時驗證有誤，是否要將畫面滾動至第一個有誤的輸入框。預設值為false

三、Form.Item 可添加的參數

以下列出我個人比較常用的，參數就如同下方程式碼說明，也可以點此連結去看更多官方 api 文件。

有三個值labelCol, wrapperCol, colon是可以在Form直接統一定義全部，也可個別在每個輸入框去設定的值。通常為了樣式統一，建議直接在Form設定即可，也可避免冗code狀況。

屬性名稱	可以使用的值	說明
label	ReactNode	該欄位顯示在畫面上的名稱
required	true 或 false	設定該欄位是否必填
rules	陣列	定義必填欄位的驗證方式，例如`rules={[{type: 'email', message: '請輸入正確的email格式',}, {required: true, message: '請填寫您的email',},]}`